Skip Headers

Oracle® Database Net Services Reference 10g Release 2 (10.2) Part Number B14213-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 7 Listener Parameters (listener.ora)

This chapter provides a complete listing of the `listener.ora` file configuration parameters.

This chapter contains these topics:

- Overview of Listener Configuration File

- Listener Parameters

## Overview of Listener Configuration File

Listener configuration, stored in the `listener.ora` file, consists of the following elements:

- Name of the listener

- Protocol addresses that the listener is accepting connection requests on

- Database services

  Dynamic service registration, a feature of Oracle9i and Oracle8, eliminates the need for static configuration of supported services. However, static service configuration is required if you plan to use Oracle Enterprise Manager.

- Control parameters

By default, the `listener.ora` file is located in the `$ORACLE_HOME/network/admin` directory on UNIX operating systems and the `ORACLE_HOME``\network\admin` directory on Windows. `listener.ora` can also be stored the following locations:

- The directory specified by the `TNS_ADMIN` environment variable or registry value

- On UNIX operating systems, the global configuration directory. For example, on the Solaris Operating System, this directory is `/var/opt/oracle`.

  See Also: Oracle operating system-specific documentation

It is possible to configure multiple listeners, each with unique name, in one `listener.ora` file. Multiple listener configuration is possible because each of the top-level configuration parameters has a suffix of the listener name or is the listener name itself.

Note: It is often useful to configure multiple listeners in one `listener.ora` file. However, Oracle Corporation recommends running only one listener for each node in most customer environments.

Example 7-1 shows a `listener.ora` file for a listener named `LISTENER`, which is the default name of the listener.

Example 7-1 Example listener.ora File

    LISTENER=
      (DESCRIPTION=
        (ADDRESS_LIST=
          (ADDRESS=(PROTOCOL=tcp)(HOST=sale-server)(PORT=1521))
          (ADDRESS=(PROTOCOL=ipc)(KEY=extproc))))
    SID_LIST_LISTENER=
      (SID_LIST=
        (SID_DESC=
          (GLOBAL_DBNAME=sales.us.acme.com)
          (ORACLE_HOME=/oracle10g)
          (SID_NAME=sales))
        (SID_DESC=
          (SID_NAME=plsextproc)
          (ORACLE_HOME=/oracle10g)
          (PROGRAM=extproc)))

## Listener Parameters

This section lists and describes the `listener.ora` file parameters. Listener configuration parameters fall into the following categories:

- Protocol Address Section

- Static Service Registration (SID_LIST) Section

- Control Parameters

### Protocol Address Section

The protocol address section of the `listener.ora` file defines the protocol addresses that the listener is accepting connection requests on. Discussed next are the most common parameters used in protocol addresses. Note that `ADDRESS_LIST` is also supported.

See Also: Chapter 4, "Protocol Address Configuration" for information about the `ADDRESS_LIST` parameter

#### DESCRIPTION

Purpose

Use the parameter `DESCRIPTION` as a container for listener protocol addresses.

Example

    listener_name=
     (DESCRIPTION=
      (ADDRESS=(PROTOCOL=tcp)(HOST=hr-server)(PORT=1521))
      (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)))

#### ADDRESS

Purpose

Use the parameter `ADDRESS` to specify a single listener protocol address.

Embed this parameter under the `DESCRIPTION` parameter.

See Also: Chapter 4, "Protocol Address Configuration" for descriptions of the correct parameters to use for each type of support protocol

Example

    listener_name=
     (DESCRIPTION=
      (ADDRESS=(PROTOCOL=tcp)(HOST=hr-server)(PORT=1521))
      (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)))

#### QUEUESIZE

Purpose

Use the parameter `QUEUESIZE` to specify the number of concurrent connection requests that the listener can accept on a TCP/IP or IPC listening endpoint (protocol address).

Embed this parameter at the end of the protocol address with its value set to the expected number of concurrent connection requests.

Default

The default number of concurrent connection requests is operating system specific. Following are the defaults for the Solaris Operating System and Windows:

- Solaris Operating System: 5

- Windows NT 4.0 Workstation: 5

- Windows NT 4.0 Server: 50

Usage Notes

See Also: Oracle Net Services Administrator's Guide for information about configuring this parameter

Example

    listener_name=
     (DESCRIPTION=
      (ADDRESS=(PROTOCOL=tcp)(HOST=hr-server)(PORT=1521)(QUEUESIZE=20)))

#### RECV_BUF_SIZE

Purpose

Use the parameter `RECV_BUF_SIZE` to specify, in bytes, the buffer space for receive operations of sessions. This parameter is supported by the TCP/IP, TCP/IP with SSL, and SDP protocols.

Note: Additional protocols might support this parameter on certain operating systems. Refer to operating-system specific documentation for information about additional protocols that support thi parameter.

Embed this parameter under the `DESCRIPTION` parameter or at the end of the protocol address with its value set to the expected number of bytes.

Default

The default value for this parameter is operating-system specific. The default for the Solaris 2.6 Operating System is 32768 bytes (32 KB).

Usage Notes

See Also: Oracle Net Services Administrator's Guide for information about configuring this parameter

Example

    listener_name=
      (DESCRIPTION=
        (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)
           (RECV_BUF_SIZE=11784))
        (ADDRESS=(PROTOCOL=ipc)(KEY=extproc)
           (RECV_BUF_SIZE=11784)))
    listener_name=
      (DESCRIPTION=
        (RECV_BUF_SIZE=11784))
        (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)
        (ADDRESS=(PROTOCOL=ipc)(KEY=extproc)))

#### SEND_BUF_SIZE

Purpose

Use the parameter `SEND_BUF_SIZE` to specify, in bytes, the buffer space for send operations of sessions. This parameter is supported by the TCP/IP, TCP/IP with SSL, and SDP protocols.

Note: Additional protocols might support this parameter on certain operating systems. Refer to operating-system specific documentation for information about additional protocols that support thi parameter.

Embed this parameter under the `DESCRIPTION` parameter or at the end of the protocol address.

Default

The default value for this parameter is operating-system specific. The default for the Solaris 2.6 Operating System is 8192 bytes (8 KB).

Usage Notes

See Also: Oracle Database Net Services Administrator's Guide for information about configuring this parameter

Example

    listener_name=
      (DESCRIPTION=
        (ADDRESS_LIST=
          (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)
           (SEND_BUF_SIZE=11280))
          (ADDRESS=(PROTOCOL=ipc)(KEY=extproc)
           (SEND_BUF_SIZE=11280))))
    listener_name=
      (DESCRIPTION=
        (ADDRESS_LIST=
          (SEND_BUF_SIZE=11280))
          (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)
          (ADDRESS=(PROTOCOL=ipc)(KEY=extproc))))

### Static Service Registration (SID_LIST) Section

You can use the `SID_LIST` section of the `listener.ora` to statically configure service information for the listener.

The `SID_LIST` section is required for Oracle8 release 8.0 or Oracle7 database services, as well as external procedure calls and Heterogeneous Services, and some management tools, including Oracle Enterprise Manager.

    SID_LIST_listener_name=
      (SID_LIST=
       (SID_DESC=
        (GLOBAL_DBNAME=global_database_name)
        (SID_NAME=sid)
        (ORACLE_HOME=oracle_home))
       (SID_DESC=...))

For later database releases, the listener uses the dynamic service information about the database and instance it has received through service registration before using statically configured information in the `listener.ora` file. Therefore, the `SID_LIST` is not required, unless Oracle Enterprise Manager is used to monitor an Oracle9i or Oracle8 database.

#### SID_LIST

Purpose

Use the parameter `SID_LIST` to identify a list of SID descriptions.

Example

    SID_LIST_listener_name=
      (SID_LIST=
       (SID_DESC=...)
       (SID_DESC=...))

#### SID_DESC

Purpose

Use the parameter `SID_DESC` to specify service information for a specific database instance or a non-database service.

Embed this parameter under the `SID_LIST` parameter.

Example

    SID_LIST_listener_name=
    (SID_LIST=
       (SID_DESC=...)
       (SID_DESC=...))

`SID_DESC` permits the following parameters:

- ENVS

- GLOBAL_DBNAME

- ORACLE_HOME

- PROGRAM

- SID_NAME

- SDU

#### E NVS

Purpose

Use the parameter `ENVS` to specify environment variables for the listener to set prior to executing (as a child process) a dedicated server program or an executable specified with the PROGRAM parameter.

Embed this parameter under the `SID_DESC` parameter.

Note: This parameter in not supported on Windows. Any process spawned by the listener will simply inherit the listener's environment.

Usage Notes

Enclose an environment variable and its value within double quotes (`"`):

    (ENVS="variable=value")

A list of environment variables and their values can be specified. Enclose the list within double quotes, from end to end, and separate environment variable definitions with commas and no space.

    (ENVS="variable=value,variable=value")

Note: Single quotes (`'`) are supported for backward compatibility.

The use of the following characters within the environment variable or its value definition `(ENVS="``variable``=``value``")` are not supported:

- Comma (`,`)

- Single quotes (`'`)

- Double quotes (`"`)

- Equal sign (`=`)

Example

    SID_LIST_listener_name=
     (SID_LIST=
      (SID_DESC=
       (SID_NAME=plsextproc)
       (ORACLE_HOME=/oracle10g)
       (PROGRAM=extproc)
       (ENVS="LD_LIBRARY_PATH=/oracle/10g/lib:/oracle/10g/ctx/lib"))
     (SID_DESC=
      (SID_NAME=test)
      (PROGRAM=/tmp/myexec)
      (ENVS="LD_LIBRARY_PATH=/private/xpm/lib:/private/mylibs,MYPATH=/usr/ucb:/usr/local/packages,APL_ENV_FILE=/apl/conf/env.txt")))

#### GLOBAL_DBNAME

Purpose

Use the parameter `GLOBAL_DBNAME` to identify the database service.

While processing a client connection request, the listener tries to match the value of this parameter with the value of the `SERVICE_NAME` parameter in the client connect descriptor. If the client connect descriptor uses the `SID` parameter, then the listener does not attempt to map the values. This parameter is primarily intended for configurations with Oracle8 release 8.0 or Oracle7 databases (where dynamic service registration is not supported for dedicated servers). This parameter may also be required for use with Oracle9i and Oracle8 database services by some configurations and management tools.

The value for this parameter is typically obtained from the combination of the `DB_NAME` and `DB_DOMAIN` parameters (`DB_NAME`.`DB_DOMAIN`) in the initialization parameter file, but the value can also contain any valid name used by clients to identify the service.

Embed this parameter under the `SID_DESC` parameter.

Example

    SID_LIST_listener_name=
      (SID_LIST=
       (SID_DESC=
        (GLOBAL_DBNAME=sales.us.acme.com)
        (SID_NAME=sales)
        (ORACLE_HOME=/usr/oracle)))

#### ORACLE_HOME

Purpose

Use the parameter `ORACLE_HOME` to identify the Oracle home location of the service.

Embed this parameter under the `SID_DESC` parameter.

Example

    SID_LIST_listener_name=
      (SID_LIST=
       (SID_DESC=
         (SID_NAME=extproc)
         (ORACLE_HOME=/usr/oracle)
         (PROGRAM=extproc)))

#### PROGRAM

Purpose

Use the parameter `PROGRAM` to identify the service executable program name.

Embed this parameter under the `SID_DESC` parameter.

Example

    SID_LIST_listener_name=
      (SID_LIST=
       (SID_DESC=
         (SID_NAME=sales)
         (ORACLE_HOME=/usr/oracle)
         (PROGRAM=extproc)))

#### SID_NAME

Purpose

Use the parameter `SID_NAME` to identify the Oracle System Identifier (SID) of the instance. You can obtain the SID value from the `INSTANCE_NAME` parameter in the initialization parameter file.

Embed this parameter under the `SID_DESC` parameter.

Example

    SID_LIST_listener_name=
      (SID_LIST=
       (SID_DESC=
        (GLOBAL_DBNAME=sales.us.acme.com)
        (SID_NAME=sales)
        (ORACLE_HOME=/usr/oracle)))

#### SDU

Purpose

Use the parameter `SDU` to instruct Oracle Net to optimize the transfer rate of data packets being sent across the network with the session data unit (SDU) size you specify.

Embed this parameter under the `SID_DESC` parameter.

Usage

See Also: Oracle Database Net Services Administrator's Guide for information about configuring this parameter

Default

2048 bytes (2KB)

Values

512 bytes to 32768 (32 KB)

Example

    SID_LIST_listener_name=
      (SID_LIST=
       (SID_DESC=
        (SDU=2085)
        (GLOBAL_DBNAME=sales.us.acme.com)
        (SID_NAME=sales)
        (ORACLE_HOME=/usr/oracle)))

### Control Parameters

This section describes the following parameters that control the behavior of the listener:

- ADMIN_RESTRICTIONS_listener_name

- INBOUND_CONNECT_TIMEOUT_listener_name

- LOG_DIRECTORY_listener_name

- LOG_FILE_listener_name

- LOGGING_listener_name

- PASSWORDS_listener_name

- SAVE_CONFIG_ON_STOP_listener_name

- SSL_CLIENT_AUTHENTICATION

- STARTUP_WAIT_TIME_listener_name

- TRACE_DIRECTORY_listener_name

- TRACE_FILE_listener_name

- TRACE_FILELEN_listener_name

- TRACE_FILENO_listener_name

- TRACE_LEVEL_listener_name

- TRACE_TIMESTAMP_listener_name

- WALLET_LOCATION

#### ADMIN_RESTRICTIONS_listener_name

Purpose

Use the parameter `ADMIN_RESTRICTIONS_``listener_name` to restrict runtime administration of the listener. The parameter is useful if the listener is not password-protected.

Setting `ADMIN_RESTRICTIONS_``listener_name``=on` disables the runtime modification of parameters in `listener.ora`. That is, the listener will refuse to accept SET commands that alter its parameters. To change any of the parameters in `listener.ora`, including `ADMIN_RESTRICTIONS_``listener_name` itself, modify the `listener.ora` file manually and reload its parameters (with the RELOAD command) for the new changes to take effect without explicitly stopping and restarting the listener.

Oracle Corporation recommends establishing a password to secure the listener. To establish an encrypted password, use either the Listener Control utility CHANGE_PASSWORD command or Oracle Net Manager.

See Also: Oracle Database Net Services Administrator's Guide for further information about password security of the listener

Default

    off

Example

    ADMIN_RESTRICTIONS_listener=on

#### INBOUND_CONNECT_TIMEOUT_listener_name

Purpose

Use the `INBOUND_CONNECT_TIMEOUT_``listener_name` parameter to specify the time, in seconds, for the client to complete its connect request to the listener after the network connection had been established.

If the listener does not receive the client request in the time specified, then it terminates the connection. In addition, the listener logs the IP address of the client and an `ORA-12525:TNS: listener has not received client's request in time allowed` error message to the `listener.log` file.

To protect both the listener and the database server, Oracle Corporation recommends setting this parameter in combination with the SQLNET.INBOUND_CONNECT_TIMEOUT parameter in the `sqlnet.ora` file. When specifying values for these parameters, consider the following recommendations:

- Set both parameters to an initial low value.

- Set the value of the `INBOUND_CONNECT_TIMEOUT_``listener_name` parameter to a lower value than the `SQLNET.INBOUND_CONNECT_TIMEOUT` parameter.

For example, you can set `INBOUND_CONNECT_TIMEOUT_``listener_name` to 2 seconds and `INBOUND_CONNECT_TIMEOUT` parameter to 3 seconds. If clients are unable to complete connections within the specified time due to system or network delays that are normal for the particular environment, then increment the time as needed.

See Also: Oracle Database Net Services Administrator's Guide for information about configuring these parameters

Default

60 seconds

Example

    INBOUND_CONNECT_TIMEOUT_listener=2

#### LOG_DIRECTORY_listener_name

Purpose

Use the parameter `LOG_DIRECTORY_``listener`_`name` to specify the destination directory of the listener log file.

Default

The `$ORACLE_HOME/network/log` directory on UNIX operating systems and the `ORACLE_HOME``\network\log` directory on Windows operating systems

Example

    LOG_DIRECTORY_listener=/oracle/network/admin/log

#### LOG_FILE_listener_name

Purpose

Use the parameter `LOG_FILE_``listener``_``name` to specify the name of the log file for the listener.

Default

`listener.log`

Example

    LOG_FILE_listener=list.log

#### LOGGING_listener_name

Purpose

Use the parameter `LOGGING_``listener``_``name` to turn logging on or off.

Default

    on

Values

    on | off

Example

    LOGGING_listener=on

#### PASSWORDS_listener_name

Purpose

Use the parameter `PASSWORDS_``listener_name` to store an encrypted password for a listener, so that certain privileges operations, such as SAVE_CONFIG and STOP, used from the Listener Control utility are secure. An encrypted password can be set using either the Listener Control utility CHANGE_PASSWORD command or Oracle Net Manager.

See Also: Oracle Database Net Services Administrator's Guide for further information about password security of the listener

Example

    PASSWORDS_LISTENER=(2D6C48144CF753AC)

#### SAVE_CONFIG_ON_STOP_listener_name

Purpose

Use the parameter `SAVE_CONFIG_ON_STOP_``listener``_``name` to specify whether or not runtime configuration changes are saved into the `listener.ora` file.

When you set the parameter to `true`, any parameters that were modified while the listener was running using the Listener Control utility SET command are saved to the `listener.ora` file when the STOP command is issued. When you set the parameter to `false`, the Listener Control utility does not save the runtime configuration changes to the `listener.ora` file.

Default

    false

Values

    true | false

Example

    SAVE_CONFIG_ON_STOP_listener=true

#### SSL_CLIENT_AUTHENTICATION

Purpose

Use the parameter `SSL_CLIENT_AUTHENTICATION` to specify whether or not a client is authenticated using the Secure Sockets Layer (SSL).

Default

    true

Values

    true | false

Usage Notes

The database server authenticates the client. Therefore, this value should be set to `false.` If this parameter is set to `true`, the listener attempts to authenticate the client, which can result in a failure.

See Also: Oracle Advanced Security Administrator's Guide

Example

    SSL_CLIENT_AUTHENTICATION=true

#### STARTUP_WAIT_TIME_listener_name

Note: This parameter is deprecated and will be desupported in a future release. If you require this parameter to run the listener, please notify Oracle Support Services.

Purpose

Use the parameter `STARTUP_WAIT_TIME_``listener``_``name` to set the number of seconds that the listener waits before responding to a Listener Control utility START command.

Default

    0

Example

    STARTUP_WAIT_TIME_listener=5

#### TRACE_DIRECTORY_listener_name

Purpose

Use the parameter `TRACE_DIRECTORY_``listener``_``name` to specify the destination directory of the listener trace file.

Default

The `$ORACLE_HOME/network/trace` directory on UNIX operating systems and the `ORACLE_HOME``\network\trace` directory on Windows

Example

    TRACE_DIRECTORY_listener=/oracle/network/admin/trace

#### TRACE_FILE_listener_name

Purpose

Use the parameter `TRACE_FILE_``listener``_``name` to specify the name of the trace file for the listener.

Default

    listener.trc

Example

    TRACE_FILE_listener=list.trc

#### TRACE_FILELEN_listener_name

Purpose

Use the parameter `TRACE_FILELEN_``listener``_``name` to specify the size of the listener trace files in kilobytes (KB). When the size is met, the trace information is written to the next file. The number of files is specified with the TRACE_FILENO_listener_name parameter.

Default

Unlimited

Example

    TRACE_FILELEN_listener=100

#### TRACE_FILENO_listener_name

Purpose

Use the parameter `TRACE_FILENO_``listener``_``name` to specify the number of trace files for listener tracing. When this parameter is set along with the TRACE_FILELEN_listener_name parameter, trace files are used in a cyclical fashion. The first file is filled first, then the second file, and so on. When the last file has been filled, the first file is re-used, and so on.

The trace file names are distinguished from one another by their sequence number. For example, if the default trace file of `listener.trc` is used, and this parameter is set to 3, the trace files would be named `listener1.trc`, `listener2.trc` and `listener3.trc`.

In addition, trace events in the trace files are preceded by the sequence number of the file.

Default

    1

Example

    TRACE_FILENO_listener=3

#### TRACE_LEVEL_listener_name

Purpose

Use the parameter `TRACE_LEVEL_``listener``_``name` to turn listener tracing on, at a specific level, or off.

Default

    off

Values

- `off` for no trace output

- `user` for user trace information

- `admin` for administration trace information

- `support` for Oracle Support Services trace information

Example

    TRACE_LEVEL_listener=admin

#### TRACE_TIMESTAMP_listener_name

Purpose

When parameter TRACE_LEVEL_listener_name is set to a specific tracing level, you can use the parameter `TRACE_TIMESTAMP_``listener``_``name` to add a time stamp in the form of `dd-mon-yyyy hh:mi:ss:mil` to every trace event in the trace file for the listener.

Default

    on

Values

`on` or `true` | `off` or `false`

Example

    TRACE_TIMESTAMP_listener=true

#### WALLET_LOCATION

Purpose

Use the parameter `WALLET_LOCATION` to specify the location of wallets. Wallets are certificates, keys, and trustpoints processed by SSL that allow for secure connections.

See Also: Oracle Advanced Security Administrator's Guide

Syntax

Oracle wallets on file system:

    WALLET_LOCATION=
      (SOURCE=
        (METHOD=file)
        (METHOD_DATA=
           (DIRECTORY=directory)
           [(PKCS11=TRUE/FALSE)]))

Microsoft certificate store:

    WALLET_LOCATION=
      (SOURCE=
         (METHOD=mcs))

Oracle wallets in the Windows registry:

    WALLET_LOCATION=
       (SOURCE=
          (METHOD=reg)
          (METHOD_DATA=
             (KEY=registry_key)))

Entrust wallets:

    WALLET_LOCATION=
       (SOURCE=
          (METHOD=entr)
          (METHOD_DATA=
             (PROFILE=file.epf)
             (INIFILE=file.ini)))

Subparameters

`WALLET_LOCATION` supports the following subparameters:

`SOURCE`: Specify the type of storage for wallets and storage location.

`METHOD`: Specify the type of storage.

`METHOD_DATA`: Specify the storage location.

`DIRECTORY`: Specify the location of Oracle wallets on file system.

`KEY`: Specify the wallet type and location in the Windows registry.

`PROFILE`: Specify the Entrust profile file (`.epf`).

`INIFILE`: Specify the Entrust initialization file (`.ini`).

Default

None

Usage Notes

- The key/value pair for Microsoft's certificate store (MCS) omits the `METHOD_DATA` parameter because MCS does not use wallets. Instead, Oracle PKI (public key infrastructure) applications obtain certificates, trustpoints and private keys directly from the user's profile.

- If an Oracle wallet is stored in the Windows registry and the wallet's `key` (`KEY)` is `SALESAPP`, the storage location of the encrypted wallet is `HKEY_CURRENT_USER\SOFTWARE\ORACLE\WALLETS\SALESAPP\EWALLET.P12`. The storage location of the decrypted wallet is `HKEY_CURRENT_USER\SOFTWARE\ORACLE\WALLETS\SALESAPP\CWALLET.SSO.`

Examples

Oracle wallets on file system:

    WALLET_LOCATION=
      (SOURCE=
          (METHOD=file)
          (METHOD_DATA=
             (DIRECTORY=/etc/oracle/wallets/databases)))

Microsoft certificate store:

    WALLET_LOCATION=
       (SOURCE=
         (METHOD=mcs))

Oracle Wallets in the Windows registry:

    WALLET_LOCATION=
       (SOURCE=
         (METHOD=REG)
         (METHOD_DATA=
            (KEY=SALESAPP)))

Entrust Wallets:

    WALLET_LOCATION=
       (SOURCE=
         (METHOD=entr)
         (METHOD_DATA=
           (PROFILE=/etc/oracle/wallets/test.epf)
           (INIFILE=/etc/oracle/wallets/test.ini)))